<?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4 fdm=marker: */

/**
 * LightBot_IProtocolAdapter 
 *
 * LICENSE
 *
 * This source file is subject to the new BSD license that is bundled
 * with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://framework.zend.com/license/new-bsd
 * If you did not receive a copy of the license and are unable to
 * obtain it through the world-wide-web, please send an email
 * to license@zend.com so we can send you a copy immediately.
 *
 * @category  LightBot
 * @package   LightBot
 * @copyright Copyright (c) 2008 Olivier Hoareau <hoareau.olivier@gmail.com>
 * @author    Olivier Hoareau <hoareau.olivier@gmail.com>
 * @license   License http://framework.zend.com/license   New BSD License
 * @version   $Id: IProtocolAdapter.php 54 2008-05-28 12:06:33Z hoareau.olivier $
 */

require_once dirname(__FILE__) . '/ILightBot.php';
require_once dirname(__FILE__) . '/ISocketAdapter.php';

// {{{ LightBot_IProtocolAdapter

/**
 * Protocol Adapter interface
 *
 * @category  LightBot
 * @package   LightBot
 * @copyright Copyright (c) 2008 Olivier Hoareau <hoareau.olivier@gmail.com>
 * @author    Olivier Hoareau <hoareau.olivier@gmail.com>
 * @license   License http://framework.zend.com/license   New BSD License
 */
interface LightBot_IProtocolAdapter
{
    // {{{ configure()

    /**
     * Configures the adapter with the specified configuration settings
     *
     * @param  mixed     $conf filename or array
     * @return LightBot_IProtocolAdapter  $this
     * @throws Exception if an error occured
     */
    public function configure($conf);

    // }}}
    // {{{ setLightBot()

    /**
     * Sets the attached light bot
     *
     * @param LightBot_ILightBot $lightBot the bot
     * @return LightBot_IProtocolAdapter $this
     */
    public function setLightBot(LightBot_ILightBot $lightBot);

    // }}}
    // {{{ getLightBot()

    /**
     * Returns the attached light bot
     *
     * @return LightBot_ILightBot the bot
     */
    public function getLightBot();

    // }}}
    // {{{ setSocketAdapter()

    /**
     * Sets the underlying socket adapter
     * 
     * @param  LightBot_ISocketAdapter $socketAdapter the socket adpater
     * @return LightBot                $this
     */
    public function setSocketAdapter(LightBot_ISocketAdapter $socketAdapter);

    // }}}
    // {{{ getSocketAdapter()

    /**
     * Returns the underlying socket adapter
     *
     * @return LightBot_ISocketAdapter the underlying socket adapter
     */
    public function getSocketAdapter();

    // }}}
    // {{{ pushMessage()

    /**
     * Pushes the specified message to the list of messages to send
     *
     * @param   array              $msg the message
     * @return  Lightbot_IProtocolAdapter $this
     */
    public function pushMessage($msg);

    // }}}
    // {{{ pushComposing()

    /**
     * Pushes the specified compose event to the list of messages to send
     *
     * @param   array              $event the event
     * @return  LightBot_IProtocolAdapter $this
     */
    public function pushComposing($event);

    // }}}
    // {{{ pushSubscriptionConfirmation()

    /**
     * Pushes the specified subscription confirmation message to the list of messages to send
     *
     * @param   array              $msg the message
     * @return  Lightbot_IProtocolAdapter $this
     */
    public function pushSubscriptionConfirmation($msg);

    // }}}
    // {{{ pushSubscriptionRequest()

    /**
     * Pushes the specified subscription request message to the list of messages to send
     *
     * @param   array              $msg the message
     * @return  Lightbot_IProtocolAdapter $this
     */
    public function pushSubscriptionRequest($msg);

    // }}}
    // {{{ pushUnsubscriptionConfirmation()

    /**
     * Pushes the specified unsubscription confirmation message to the list of messages to send
     *
     * @param   array              $msg the message
     * @return  Lightbot_IProtocolAdapter $this
     */
    public function pushUnsubscriptionConfirmation($msg);

    // }}}
    // {{{ pushUnsubscriptionRequest()

    /**
     * Pushes the specified unsubscription request message to the list of messages to send
     *
     * @param   array              $msg the message
     * @return  Lightbot_IProtocolAdapter $this
     */
    public function pushUnsubscriptionRequest($msg);

    // }}}
    // {{{ pushError()

    /**
     * Pushes the specified error message to the list of messages to send
     *
     * @param   array              $msg the message
     * @return  Lightbot_IProtocolAdapter $this
     */
    public function pushError($msg);

    // }}}
    // {{{ pushPresence()

    /**
     * Pushes the specified presence message to the list of messages to send
     *
     * @param   array              $msg the message
     * @return  Lightbot_IProtocolAdapter $this
     */
    public function pushPresence($msg);

    // }}}
    // {{{ pushListContactRequest()

    /**
     * Pushes the specified contact list event to the list of messages to send
     *
     * @param   array              $msg the message
     * @return  Lightbot_IProtocolAdapter $this
     */
    public function pushListContactRequest($msg);

    // }}}
    // {{{ pushContactVCardRequest()

    /**
     * Pushes the specified contact VCard request event to the list of messages to send
     *
     * @param   array              $msg the message
     * @return  LightBot_IProtocolAdapter $this
     */
    public function pushContactVCardRequest($msg);

    // }}}
    // {{{ pushAddContact()

    /**
     * Pushes the specified contact add event to the list of messages to send
     *
     * @param   array              $event the event
     * @return  LightBot_IProtocolAdapter $this
     */
    public function pushAddContact($event);

    // }}}
    // {{{ pushRemoteAction()

    /**
     * Pushes the specified remote action to the list of remote action to execute
     *
     * @param string the remote uri of the action
     * @return LightBot_IProtocolAdapter $this
     */

    public function pushRemoteAction($uri,$params=null);

    // }}}
    // {{{ pushRemoveContact()

    /**
     * Pushes the specified contact remove event to the list of messages to send
     *
     * @param   array              $event the event
     * @return  LightBot_IProtocolAdapter $this
     */
    public function pushRemoveContact($event);

    // }}}
    // {{{ ping()

    /**
     * Pings the remote server if needed
     *
     * @param  resource  $socket the socket
     * @return LightBot  $this
     * @throws Exception if socket is null or closed
     */
    public function ping();

    // }}}
}   

// }}}

/*
 * Local variables:
 * tab-width: 4
 * c-basic-offset: 4
 * c-hanging-comment-ender-p: nil
 * End:
 */
